heroku-client
A wrapper around the v3 Heroku API.
Install
$ npm install heroku-client --save
Documentation
Docs are auto-generated and live in the
docs directory.
Usage
heroku-client
works by providing functions that return proxy objects for
interacting with different resources through the Heroku API.
To begin, require the Heroku module and create a client, passing in an API
token:
var Heroku = require('heroku-client'),
heroku = new Heroku({ token: process.env.HEROKU_API_TOKEN });
The simplest example is listing a user's apps. First, we call heroku.apps()
,
which returns a proxy object to the /apps endpoint, then we call list()
to
actually perform the API call:
heroku.apps().list(function (err, apps) {
});
The advantage of using proxy objects is that they are reusable. Let's get the
info for the user's app "my-app", get the dynos for the app, and
remove a collaborator:
var app = heroku.apps('my-app');
app.info(function (err, app) {
});
app.dynos().list(function (err, dynos) {
});
app.collaborators('user@example.com').delete(function (err, collaborator) {
});
Requests that require a body are easy, as well. Let's add a collaborator to
the user's app "another-app":
var app = heroku.apps('another-app'),
user = { email: 'new-user@example.com' };
app.collaborators().create({ user: user }, function (err, collaborator) {
});
Generic Requests
heroku-client has get
, post
, patch
, and delete
functions which can make
requests with the specified HTTP method to any endpoint:
heroku.get('/apps', function (err, apps) {
});
heroku.post('/apps', function (err, app) {
});
heroku.post('/apps', { name: 'my-new-app' }, function (err, app) {
});
heroku.patch('/apps/my-app', { name: 'my-renamed-app' }, function (err, app) {
});
heroku.delete('/apps/my-old-app', function (err, app) {
});
There is also an even more generic request
function that can accept many more
options:
heroku.request({
method: 'GET',
path: '/apps',
headers: {
'Foo': 'Bar'
},
parseJSON: false
}, function (err, responseBody) {
});
Promises
heroku-client works with Node-style callbacks, but also implements promises with
the Q library.
var q = require('q');
heroku.apps().list().then(function (apps) {
return q.all(apps.map(function (app) {
return heroku.apps(app.name).dynos().list();
}));
}).then(function (dynos) {
console.log(dynos);
});
Generators
It's easy to get heroku-client working with generators. In this
example, I'll use the co library to wrap a function that will get the list
of all of my apps, and then get the dynos for each of those apps:
let co = require('co');
let heroku = require('heroku-client');
let hk = heroku.createClient({ token: process.env.HEROKU_API_KEY });
let main = function* () {
let apps = yield hk.apps().list();
let dynos = yield apps.map(getDynos);
console.log(dynos);
function getDynos(app) {
return hk.apps(app.name).dynos().list();
}
};
co(main)();
As long as you're using Node >= 0.11, you can run this script with:
$ node --harmony --use-strict file.js
Hooray, no callbacks or promises in sight!
HTTP Proxies
If you'd like to make requests through an HTTP proxy, set the
HEROKU_HTTP_PROXY_HOST
environment variable with your proxy host, and
HEROKU_HTTP_PROXY_PORT
with the desired port (defaults to 8080). heroku-client
will then make requests through this proxy instead of directly to
api.heroku.com.
Caching
heroku-client can optionally perform caching of API requests.
heroku-client will cache any response from the Heroku API that comes with an
ETag
header, and each response is cached individually (i.e. even though the
client might make multiple calls for a user's apps and then aggregate them into
a single JSON array, each required API call is individually cached). For each
API request it performs, heroku-client sends an If-None-Match
header if there
is a cached response for the API request. If API returns a 304 response code,
heroku-client returns the cached response. Otherwise, it writes the new API
response to the cache and returns that.
To tell heroku-client to perform caching, call the configure
function.
Caching requires an encryption key to encrypt the results prior to caching.
This must be set in the environment variable HEROKU_CLIENT_ENCRYPTION_SECRET.
HEROKU_CLIENT_ENCRYPTION_SECRET
should be a long, random string of characters.
heroku-client includes bin/secret
as one way of generating
values for this variable. Do not publish this secret or commit it to source
control. If it's compromised, flush your memcache and generate a new encryption
secret.
Caching with memjs
If cache
is the boolean value true
then heroku-client will use memjs
for caching.
Example:
var Heroku = require('heroku').configure({ cache: true });
This requires a MEMCACHIER_SERVERS
environment variable, as well as a
HEROKU_CLIENT_ENCRYPTION_SECRET
environment variable that heroku-client uses
to build cache keys and encrypt cache contents.
MEMCACHIER_SERVERS
can be a single hostname:port
memache address, or a
comma-separated list of memcache addresses, e.g.
example.com:11211,example.net:11211
. Note that while the environment variable
that memjs looks for is
named for the MemCachier service it was originally built for, it
will work with any memcache server that speaks the binary protocol.
Custom caching
Alternatively you can specify a custom cache implementation. Your custom implementation must define get(key, cb(err, value))
and set(key, value)
functions.
Here's a sample implementation that uses Redis to cache API responses for 5-minutes each:
var redis = require('redis');
var client = redis.createClient();
var cacheTtlSecs = 5 * 60;
var redisCache = {
get: function(key, cb) {
var redisKey = 'heroku:api:' + key;
client.GET(redisKey, cb);
},
set: function(key, value) {
var redisKey = 'heroku:api:' + key;
client.SETEX(redisKey, cacheTtlSecs, value, function(err) {
});
}
};
var Heroku = require('heroku-client');
Heroku.configure({
cache: redisCache
});
Contributing
Updating resources
To fetch the latest schema, generate documentation, and run the tests:
$ bin/update
Inspect your changes, and
bump the version number accordingly when cutting a
release.
Generating documentation
Documentation for heroku-client is auto-generated from
the API schema.
Docs are generated like so:
$ bin/docs
Generating docs also runs a cursory test, ensuring that every documented
function is a function that can be called.
Running tests
heroku-client uses jasmine-node for tests:
$ npm test